Create or Update Risk Assessment

Request to send a card transaction to a risk service provider without processing a payment.
You can use this operation when you want to:

  • Assess risk: request the risk service provider to assess the risk of a card transaction and provide a result. In this case set requestAction to RISK_ASSESSMENT.
  • Provide information only: inform the risk service provider about a card transaction or the outcome of processing a card transaction. You do not require the risk service provider to provide a risk assessment result. In this case set requestAction to INFORMATION_ONLY and provide details about the transaction processing result in the transactionProcessingResponse parameter group.
You can submit more than one risk assessment request for the same payment by using the same risk assessment ID. For example, you might want to assess the risk of a transaction before processing the payment and then provide an update to the risk service provider after it has been processed. Note that if the previous risk assessment was not successful (result=FAILURE) you must use a new risk assessment ID.

GET https://test-bankalfalah.gateway.mastercard.com/api/nvp/version/69

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • To authenticate to the API two additional NVP parameters must be supplied in the request. Provide 'merchant.<your gateway merchant ID>' in the apiUsername field and your API password in the apiPassword field.

Request

Fields

agreement OPTIONAL

A commercial agreement you have with the payer that allows you to store and use their payment details for later payments.

For example, an agreement to a series of recurring payments (a mobile phone subscription), an agreement to take payment for a purchase by a series of installments (hire purchase), an agreement to make additional payments when required (account top up), or to fulfil a standard industry practice (no show penalty charge).

Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.

See Credential on File, Cardholder, and Merchant Initiated Transactions for details.

agreement.type Enumeration OPTIONAL

The type of commercial agreement that the payer has with you.

Specify the agreement type when you have provided a value for agreement.id and this payment is the first in a series of payments. The default value is OTHER.

The gateway will use the value you specify for subsequent payments in the series.

Value must be a member of the following list. The values are case sensitive.

INDUSTRY_PRACTICE

An agreement where the payer authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. These additional payments are triggered by an event not known at the time of the payer's initial agreement. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show charge when the payer fails to show for a booking.

INSTALLMENT

An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.

OTHER

An agreement where you want to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.

RECURRING

An agreement where the payer authorizes you to process repeat payments for bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.

UNSCHEDULED

An agreement where the payer authorizes you to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

airline OPTIONAL

Airline industry specific data.

airline.bookingReference Alphanumeric OPTIONAL

The record locator used to access a specific Passenger Name Record (PNR).

PNR is a record in the database of a booking system that contains the itinerary for a passenger, or a group of passengers traveling together.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 6 Max length: 15
airline.documentType Enumeration OPTIONAL

The type of charge associated with the transaction.

Document Type Code

Value must be a member of the following list. The values are case sensitive.

ADDITIONAL_COLLECTION

Additional Collection

AGENCY_EXCHANGE_ORDER

Agency Exchange Order

AGENCY_GROUP_TICKET

Agency Group Ticket

AGENCY_MISCELLANEOUS_CHARGE_ORDER

Agency Misc. Charge Order (MCO)

AGENCY_PASSENGER_TICKET

Agency Passenger Ticket

AGENCY_TOUR_ORDER_OR_VOUCHER

Agency Tour Order/Voucher

AIR_FREIGHT

SPD/Air Freight

ANIMAL_TRANSPORTATION_CHARGE

Animal Transportation Charge

CATALOGUE_MERCHANDISE_ORDERED

Catalogue Merchandise Ordered

CLUB_MEMBERSHIP_FEE

Club Membership Fee

COUPON_BOOK

Coupon Book

CREDIT_CLASS_SERVICE_ADJUSTMENT

Credit Class of Service Adjustment

CREDIT_DENIED_BOARDING

Credit Denied Boarding

CREDIT_EXCHANGE_REFUND

Credit Exchange Refund

CREDIT_LOST_TICKET_REFUND

Credit Lost Ticket Refund

CREDIT_MISCELLANEOUS_REFUND

Credit Misc. Refund

CREDIT_MULTIPLE_UNUSED_TICKETS

Credit Multiple Unused Tickets

CREDIT_OVERCHARGE_ADJUSTMENT

Credit Overcharge Adjustment

CREDIT_UNUSED_TRANSPORTATION

Credit Unused Transportation

DEBT_ADJUSTMENT_DUPLICATE_REFUND_OR_USE

Debt Adjustment Duplicate Refund/Use

DUTY_FREE_SALE

Duty Free Sale

EXCESS_BAGGAGE

Excess Baggage

EXCHANGE_ADJUSTMENT

Exchange Adjustment

EXCHANGE_ORDER

Exchange Order

FIREARMS_CASE

Firearms Case

FREQUENT_FLYER_FEE_OR_PURCHASE

Frequent Flyer Fee/Purchase

FREQUENT_FLYER_FULFILLMENT

Frequent Flyer Fulfillment

FREQUENT_FLYER_OVERNIGHT_DELIVERY_CHARGE

Frequent Flyer Overnight Delivery Charge

GROUP_TICKET

Group Ticket

IN_FLIGHT_ADJUSTMENT

In-flight Adjustment

IN_FLIGHT_CHARGES

In-flight Charges

IN_FLIGHT_DUTY_FREE_PURCHASE

In-flight Duty Free Purchase

IN_FLIGHT_MERCHANDISE_ORDERED

In-flight Merchandise Ordered

IN_FLIGHT_PHONE_CHARGES

In-flight Phone Charges

KENNEL_CHARGE

Kennel Charge

LOST_TICKET_APPLICATION

Lost Ticket Application

MISCELLANEOUS_CHARGE_ORDER_OR_PREPAID_TICKET_ADVICE

Misc. Charge Order (MCO) / Prepaid Ticket Auth.

MISCELLANEOUS_TAXES_FEES

Miscellaneous Tax(es) Fee(s)

PASSENGER_TICKET

Passenger Ticket

SELF_SERVICE_TICKETS

Self-Service Ticket(s)

SENIOR_CITIZEN_DISCOUNT_BOOKLETS

Senior Citizen Discount Booklets

SMALL_PACKAGE_DELIVERY

Small Package Delivery

SPECIAL_SERVICE_TICKET

Special Service Ticket

SUPPORTED_REFUND

Supported Refund

TICKET_BY_MAIL

Ticket by Mail

TOUR_DEPOSIT

Tour Deposit

TOUR_ORDER_VOUCHER

Tour Order Voucher

UNDERCHARGE_ADJUSTMENT

Undercharge Adjustment

UNSUPPORTED_REFUND

Unsupported Refund

UPGRADE_CHARGE

Upgrade Charge

VENDOR_REFUND_CREDIT

Vendor Refund Credit

VENDOR_SALE

Vendor Sale

airline.itinerary OPTIONAL

Itinerary details

airline.itinerary.leg[n] OPTIONAL

Travel leg details.

airline.itinerary.leg[n].carrierCode Regex OPTIONAL

The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier for the trip leg.

Data must match regex

regex \w{2}|\d{3}|\w{2}/\d{3} message Carrier code must be 2 characters, 3 digits or a combination of both in the format: ZZ/999
airline.itinerary.leg[n].conjunctionTicketNumber Alphanumeric OPTIONAL

The ticket containing the coupon for this leg for an itinerary with more than four trip legs.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.itinerary.leg[n].couponNumber Alphanumeric OPTIONAL

The coupon number on the ticket for the trip leg.

Each trip leg requires a separate coupon. The coupon within the series is identified by the coupon number.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 1
airline.itinerary.leg[n].departureAirport Upper case alphabetic text OPTIONAL

The 3 character IATA airport code of the departure airport for the trip leg.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.itinerary.leg[n].departureDate Date OPTIONAL

Date of departure for the trip leg.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

airline.itinerary.leg[n].departureTax Decimal OPTIONAL

Tax payable on departure for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].departureTime Time OPTIONAL

Departure time in local time for the departure airport for this trip leg.

Data must comply with ISO 8601 extended time formats, hh:mm[:ss]Z or hh:mm[:ss](+/-)hh[:mm]

airline.itinerary.leg[n].destinationAirport Upper case alphabetic text OPTIONAL

The 3 character IATA airport code for the destination airport for the trip leg.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.itinerary.leg[n].destinationArrivalDate Date OPTIONAL

Arrival date in local time for the destination airport for this trip leg.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

airline.itinerary.leg[n].destinationArrivalTime Time OPTIONAL

Arrival time in local time for the destination airport for this trip leg.

Data must comply with ISO 8601 extended time formats, hh:mm[:ss]Z or hh:mm[:ss](+/-)hh[:mm]

airline.itinerary.leg[n].endorsementsRestrictions Alphanumeric OPTIONAL

Restrictions (e.g. non-refundable) or endorsements applicable to the trip leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 20
airline.itinerary.leg[n].exchangeTicketNumber Alphanumeric OPTIONAL

New ticket number issued when a ticket is exchanged for the trip leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.itinerary.leg[n].fare Decimal OPTIONAL

Total fare payable for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].fareBasis Alphanumeric OPTIONAL

Code defining the rules forming the basis of the fare (type of fare, class entitlement, etc.)

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 24
airline.itinerary.leg[n].fees Decimal OPTIONAL

Total fees payable for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].flightNumber Alphanumeric OPTIONAL

The flight number for the trip leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 4 Max length: 6
airline.itinerary.leg[n].stopoverPermitted Boolean OPTIONAL

Indicates if a stopover is permitted for the trip leg.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.itinerary.leg[n].taxes Decimal OPTIONAL

Total taxes payable for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].travelClass Alphanumeric OPTIONAL

The industry code indicating the class of service (e.g. Business, Coach) for the leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 3
airline.itinerary.numberInParty Digits OPTIONAL

Number of passengers associated with this booking.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 3
airline.itinerary.originCountry Upper case alphabetic text OPTIONAL

The 3 character ISO 3166-1 alpha-3 country code of the country of origin for the itinerary.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.passenger[n] OPTIONAL

Passenger details

airline.passenger[n].firstName String OPTIONAL

First name of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 50
airline.passenger[n].frequentFlyerNumber String OPTIONAL

Frequent Flyer or Loyalty Program number for this passenger.

Data can consist of any characters

Min length: 1 Max length: 20
airline.passenger[n].lastName String OPTIONAL

Last name of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 20
airline.passenger[n].middleName String OPTIONAL

Middle name of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 50
airline.passenger[n].specificInformation Alphanumeric OPTIONAL

Passenger specific information recorded on the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 59
airline.passenger[n].title String OPTIONAL

Title of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 20
airline.planNumber Alphanumeric OPTIONAL

Plan number supplied by the airline for this booking.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 2 Max length: 2
airline.ticket OPTIONAL

Ticket details

airline.ticket.conjunctionTicketIndicator Boolean OPTIONAL

Indicates if a conjunction ticket with additional coupons was issued.

Conjunction ticket refers to two or more tickets concurrently issued to a passenger and which together constitute a single contract of carriage.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.ticket.eTicket Boolean OPTIONAL

Indicates if an electronic ticket was issued.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.ticket.exchangedTicketNumber Alphanumeric OPTIONAL

The original ticket number when this is a transaction for an exchanged ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.ticket.issue OPTIONAL

Ticket issue information.

airline.ticket.issue.address String OPTIONAL

The address where the ticket was issued.

Data can consist of any characters

Min length: 1 Max length: 16
airline.ticket.issue.carrierCode Regex OPTIONAL

The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier issuing the ticket.

Data must match regex

regex \w{2}|\d{3}|\w{2}/\d{3} message Carrier code must be 2 characters, 3 digits or a combination of both in the format: ZZ/999
airline.ticket.issue.carrierName Alphanumeric OPTIONAL

Name of airline carrier issuing the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 25
airline.ticket.issue.city Alphanumeric OPTIONAL

The city/town where the ticket was issued.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 18
airline.ticket.issue.country Upper case alphabetic text OPTIONAL

The 3 character ISO 3166-1 alpha-3 country code of the country where the ticket was issued.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.ticket.issue.date Date OPTIONAL

The date the ticket was issued.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

airline.ticket.issue.travelAgentCode Alphanumeric OPTIONAL

Industry code of the travel agent issuing the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 8 Max length: 9
airline.ticket.issue.travelAgentName Alphanumeric OPTIONAL

Name of the travel agent issuing the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 30
airline.ticket.restricted Boolean OPTIONAL

Indicates if the issued ticket is refundable.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.ticket.taxOrFee[n] OPTIONAL

Breakdown of the ticket taxes, airport taxes, charges and fees for an airline ticket purchase.

The total of the amounts in this group should equal the sum of the airline.ticket.totalFees and airline.ticket.totalTaxes fields.

airline.ticket.taxOrFee[n].amount Decimal OPTIONAL

The tax, charge or fee amount payable.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.ticket.taxOrFee[n].type Alphanumeric OPTIONAL

The tax, charge or fee type code as assigned by IATA.

For example, the IATA tax/ charge/ fee type for Passenger Movement Charge (PMC) in Australia is TT1.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 3 Max length: 3
airline.ticket.ticketNumber Alphanumeric OPTIONAL

The airline ticket number associated with the transaction.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.ticket.totalFare Decimal OPTIONAL

Total fare for all trip legs on the ticket.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.ticket.totalFees Decimal OPTIONAL

Total fee for all trip legs on the ticket.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.ticket.totalTaxes Decimal OPTIONAL

Total taxes for all trip legs on the ticket.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.transactionType Enumeration OPTIONAL

The type of transaction performed against this airline booking.

Transaction Type

Value must be a member of the following list. The values are case sensitive.

EXCHANGE_TICKET

Exchange Ticket

MISCELLANEOUS_CHARGE

Miscellaneous Charge

REFUND

Refund

REVERSAL

Reversal

TICKET_PURCHASE

Ticket Purchase

TOUR_ORDER

Tour Order

apiOperation String = CREATE_OR_UPDATE_RISK_ASSESSMENT FIXED

Any sequence of zero or more unicode characters.

authentication OPTIONAL

Information about how the payer's identity is verified.

For example, using 3-D Secure authentication.

This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.

authentication.3ds OPTIONAL

Information about payer authentication using 3-D Secure authentication.

Only provide these fields if you authenticated the payer using a different 3-D Secure service provider. If you authenticated the payer using the gateway, then provide authentication.transactionId instead.

Parameters in this group apply to both 3-D Secure authentication version 1 and 3-D Secure Authentication version 2.

Depending on the 3-D Secure authentication version applicable you will also need additional parameters:

- 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
- 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.

authentication.3ds.acsEci Alphanumeric OPTIONAL

Indicates the security level of the transaction.

This is the Electronic Commerce Indicator (ECI) value provided by the issuer's Access Control Server (ACS) to indicate the results of the attempt to authenticate the payer.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 2
billing OPTIONAL

Details of the payer's billing address.

billing.address OPTIONAL

The payer's billing address.

This data may be used to qualify for better interchange rates on corporate purchase card transactions.

billing.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.company String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
billing.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
billing.address.stateProvince String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode String OPTIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
billing.address.street String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.street2 String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
correlationId String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
cruise OPTIONAL

Cruise industry data.

cruise.bookingReference String OPTIONAL

The cruise booking reference.

Data can consist of any characters

Min length: 1 Max length: 12
cruise.company OPTIONAL

Information about the cruise line.

cruise.company.contact OPTIONAL

Contact details of the cruise line.

cruise.company.contact.companyPhone Telephone Number OPTIONAL

The cruise line registered office telephone number in ITU-T E123 format.

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
cruise.company.contact.customerServicePhone Telephone Number OPTIONAL

The customer service phone number in ITU-T E123 format.

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
cruise.departurePort OPTIONAL

A departurePort is the port where the passenger(s) boarded the cruise ship when the cruise trip started

cruise.departurePort.address OPTIONAL

Address of the cruise line.

cruise.departurePort.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
cruise.departurePort.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
cruise.departurePort.address.postCodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
cruise.departurePort.address.stateProvinceCode String OPTIONAL

The state or province code of the address.

The value must match the second part of the ISO 3166-2 code. For an address in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP. For an address in Canada provide the 2-letter ISO 3166-2 province code.

Data can consist of any characters

Min length: 1 Max length: 3
cruise.departurePort.address.street String OPTIONAL

The first line of the address.

Data can consist of any characters

Min length: 1 Max length: 100
cruise.departurePort.address.street2 String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
cruise.passenger[n] OPTIONAL

Cruise passenger details.

cruise.passenger[n].firstName String OPTIONAL

The first name of the passenger.

Data can consist of any characters

Min length: 1 Max length: 50
cruise.passenger[n].folioNumber String OPTIONAL

The folio number assigned to the passenger.

Data can consist of any characters

Min length: 1 Max length: 30
cruise.passenger[n].lastName String OPTIONAL

The last name of the passenger.

Data can consist of any characters

Min length: 1 Max length: 50
cruise.passenger[n].middleName String OPTIONAL

The middle name of the passenger.

Data can consist of any characters

Min length: 1 Max length: 50
cruise.passenger[n].title String OPTIONAL

The title of the passenger.

Data can consist of any characters

Min length: 1 Max length: 50
cruise.returnDate Date OPTIONAL

The cruise return/ sail end date.

This field is required when cruise.departureDate is provided and the value must be equal to or later than cruise.departureDate.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

cruise.shipName String OPTIONAL

The name of the cruise ship.

Data can consist of any characters

Min length: 1 Max length: 50
cruise.travelAgentCode Alphanumeric OPTIONAL

The industry code of the travel agent booking the cruise.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 8 Max length: 9
cruise.travelAgentName String OPTIONAL

The name of the travel agent booking the cruise.

Data can consist of any characters

Min length: 1 Max length: 30
cruise.travelPackageItems Comma separated enumeration OPTIONAL

A comma separated list of the travel items that are included as part of a cruise travel package.

If the value CRUISE_ONLY is provided then other items are not permitted in the list.

Value must be one or more comma separated members of the following list. The values are case sensitive.

CAR_RENTAL

Car rental is included in the travel package.

CRUISE_ONLY

No additional items are included in the cruise travel package.

FLIGHT

Flights are included in the travel package.

customer OPTIONAL

Information about the customer, including their contact details.

customer.email Email OPTIONAL

The email address of the customer.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

customer.mobilePhone Telephone Number OPTIONAL

The payer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
customer.phone Telephone Number OPTIONAL

The payer's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
device OPTIONAL

Information about the device used by the payer for this transaction.

device.browser String OPTIONAL

The User-Agent header of the browser the customer used to place the order.

For example, MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)

Data can consist of any characters

Min length: 1 Max length: 255
device.fingerprint String OPTIONAL

Information collected about a remote computing device for the purpose of providing a unique identifier for the device.

For example, session ID, blackbox ID.

Data can consist of any characters

Min length: 1 Max length: 4000
device.ipAddress String OPTIONAL

The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format.

Data can consist of any characters

Min length: 7 Max length: 15
device.mobilePhoneModel String OPTIONAL

The mobile phone manufacturer's identifier for the model of the mobile device used to initiate the payment.

Data can consist of any characters

Min length: 1 Max length: 255
merchant Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
order REQUIRED

Information about the order associated with this transaction.

order.amount Decimal OPTIONAL

The total amount for the order.  This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.

The value of this field in the response is zero if payer funds are not transferred.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.cashbackAmount Decimal OPTIONAL

The amount the payer has chosen to receive as cash in addition to the amount they are paying for the goods or services they are purchasing from you.

The cash back amount is included in the total amount of the order you provide in order.amount.

This field corresponds to EMV tag 9F03

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.currency Upper case alphabetic text REQUIRED

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.description String OPTIONAL

Short textual description of the contents of the order.

Data can consist of any characters

Min length: 1 Max length: 127
order.discount OPTIONAL

Information about a price reduction you have applied to the order.

For example, you may apply discounts for trade, employees, bulk purchase, or a sales promotion.

order.discount.amount Decimal OPTIONAL

The total amount of the discount you have applied to the order.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.discount.code String OPTIONAL

The code you use to identify the reason for the discount.

Data can consist of any characters

Min length: 1 Max length: 40
order.item[n] OPTIONAL

Information about the items the payer purchases with the order.

order.item[n].brand String OPTIONAL

The brand of the item.

For example, Dell.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].category String OPTIONAL

Your category for the item.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].name String REQUIRED

A short name describing the item.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].quantity Decimal REQUIRED

The quantity of the item.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number greater than zero.

Min length: 0 Max length: 30
order.item[n].sku String OPTIONAL

The SKU (Stock Keeping Unit) or the item identifier for this item.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].unitPrice Decimal REQUIRED

The cost price for the item.

This amount is multiplied with the item quantity (item.quantity) to determine the total amount for this item (item.amount). This amount does not include the tax amount and/or discount amount applicable to this item.

Data is a string that consists of the characters 0-9, '.' and '-' and represents a valid decimal number.

Min length: 1 Max length: 14
order.walletProvider Enumeration OPTIONAL

Details about the source of the payment details used for digital payment methods.

Provide this value when you process payments for:

  • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
  • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.

Value must be a member of the following list. The values are case sensitive.

APPLE_PAY

Apple Pay mobile wallet provider.

GOOGLE_PAY

Google Pay mobile wallet provider.

SAMSUNG_PAY

Samsung Pay mobile wallet provider.

SECURE_REMOTE_COMMERCE

Secure Remote Commerce (SRC) wallet provider.

requestAction Enumeration REQUIRED

Informs the risk service provider how you want them to process the information you have provided in the request.

Informs the risk service provider how you want them to process the information you have provided in the request..

Value must be a member of the following list. The values are case sensitive.

INFORMATION_ONLY

You are informing the risk service provider about a card transaction or the outcome of a card transaction. You do not require the risk service provider to provide a risk assessment result.

RISK_ASSESSMENT

You are requesting the risk service provider to assess the risk of a card transaction and provide a risk assessment result.

riskassessment Alphanumeric + additional characters REQUIRED

A unique identifier for this risk assessment to distinguish it from any other risk assessment you create.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'

Min length: 1 Max length: 40
shipping OPTIONAL

Shipping information for this order.

shipping.address OPTIONAL

The address to which this order will be shipped.

shipping.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.company String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
shipping.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
shipping.address.stateProvince String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
shipping.address.street String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.street2 String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
shipping.contact OPTIONAL

Details of the contact person at the address the goods will be shipped to.

shipping.contact.email Email OPTIONAL

The contact person's email address.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

shipping.contact.firstName String OPTIONAL

The first name of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.lastName String OPTIONAL

The last name or surname of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.mobilePhone Telephone Number OPTIONAL

The contact person's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
shipping.contact.phone Telephone Number OPTIONAL

The contact person's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
shipping.method Enumeration OPTIONAL

The shipping method used for delivery of this order.

Value must be a member of the following list. The values are case sensitive.

ELECTRONIC

Electronic delivery.

GROUND

Ground (4 or more days).

NOT_SHIPPED

Order for goods that are not shipped (for example, travel and event tickets)

OVERNIGHT

Overnight (next day).

PICKUP

Shipped to a local store for pick up.

PRIORITY

Priority (2-3 days).

SAME_DAY

Same day.

sourceOfFunds REQUIRED

Information about the payment type selected by the payer for this payment and the source of the funds.

Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.

sourceOfFunds.provided REQUIRED

Information about the source of funds when it is directly provided (as opposed to via a token or session).

For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.

sourceOfFunds.provided.card REQUIRED

Details about the card.

Use this parameter group when you have sourced payment details using:
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).

sourceOfFunds.provided.card.devicePayment OPTIONAL

Details about the card that you have sourced using digital payment methods.

Use this parameter group when you have sourced payment details using:

  • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
  • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
  • • Card scheme tokens. This applies when you have tokenized the payer's card number using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES) or Visa Token Service (VTS).

sourceOfFunds.provided.card.devicePayment.3DSecure OPTIONAL

Details used to process a digital payment where the payment data keys for the online payment cryptogram are provided using the 3-D Secure format.

Use this parameter group for:

  • • Device payments: if you decrypt the payment token yourself. In this case, you source these fields directly from the decrypted payment token.
    You do not need to use this parameter group if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken.
  • • Card scheme tokens: if you decrypt the transaction credentials yourself.

sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator Digits OPTIONAL

The Electronic Commerce Indicator generated for payments made using a device payment method.

You source this field directly from the decrypted payment token.

You must provide this field if you have it. This field is not applicable for payments using digital wallets.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 2
sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram Base64 OPTIONAL

A cryptogram used to authenticate the transaction.

Use this field for:

  • • Device payments: source this field directly from the decrypted payment token.
  • • Card scheme tokens: source this field directly from the decrypted transaction credentials. For MDES (Mastercard Digital Enablement Service) tokens this is the UCAF cryptogram (de48se43Data). For VTS (Visa Token Service) tokens this is the TAVV cryptogram.

Data is Base64 encoded

Min length: 1 Max length: 128
sourceOfFunds.provided.card.expiry OPTIONAL

Expiry date, as shown on the card or as provided for a card scheme token.

This field corresponds to EMV tag 5F24

sourceOfFunds.provided.card.expiry.month Digits REQUIRED

Month, as shown on the card.

Months are numbered January=1, through to December=12.

Data is a number between 1 and 12 represented as a string.

sourceOfFunds.provided.card.expiry.year Digits REQUIRED

Year, as shown on the card.

The Common Era year is 2000 plus this value.

Data is a string that consists of the characters 0-9.

Min length: 2 Max length: 2
sourceOfFunds.provided.card.nameOnCard String OPTIONAL

The cardholder's name as printed on the card.

Data can consist of any characters

Min length: 1 Max length: 256
sourceOfFunds.provided.card.number Digits OPTIONAL

The account number of the payer's account used for the payment.

On requests, provide the number in the form that you receive it (as explained below). On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).

  • Request

    On request, populate this field based on the payment method you are using for the payment:
    • • Card: the account number embossed onto the card. This field corresponds to EMV tag 5A.
    • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay. Normally for device payments, you would populate sourceOfFunds.provided.card.devicePayment.paymentToken and the gateway will decrypt and extract this field. However, you can populate this field if you decrypt the payment token yourself. In this case use the Device PAN (DPAN) provided in the payment token.
    • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout. In this case, provide the PAN retrieved from the wallet.
    • • Scheme tokens such as MDES (Mastercard Digital Enablement Service) or Visa Token Service (VTS). For MDES tokens, supply the value called the "Token PAN". For VTS tokens, supply the value called "Token"
  • Response

    On return, the card number will be populated in 6.4 masking format, for example, 000000xxxxxx0000. If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.

    When a DPAN or scheme token was provided in the transaction request, then this field will represent the PAN of the associated payer's account (when supported by the acquirer). This is also referred to as the Funding PAN (FPAN).

Data is a string that consists of the characters 0-9.

Min length: 9 Max length: 19
sourceOfFunds.provided.card.paymentAccountReference String OPTIONAL

The unique identifier that links a Primary Account Number (PAN) for a card with all Device Primary Account Numbers (DPANs) or card scheme tokens issued for the card.

Data can consist of any characters

Min length: 29 Max length: 29
sourceOfFunds.provided.card.securityCode Digits OPTIONAL

Card verification code, as printed on the back or front of the card or as provided for a card scheme token.

Data is a string that consists of the characters 0-9.

Min length: 3 Max length: 4
sourceOfFunds.provided.card.storedOnFile Enumeration OPTIONAL

This field only applies if you collect card details from your payer, store them, and either you or your payer use the stored credentials for subsequent payments.

Refer to Credential on File, Cardholder and Merchant-initiated Transactions for details.

Value must be a member of the following list. The values are case sensitive.

NOT_STORED

Set this value if you are not storing the card details provided by the payer for this transaction. The gateway sets this value by default, if you are submitting a payer-initiated transaction. You must not use this value when submitting merchant-initiated transactions.

STORED

Set this value if you have previously stored the card details provided by the payer and are now using these stored details. The gateway sets this value by default, if you are submitting a merchant-initiated transaction.

TO_BE_STORED

Set this value if this is the first transaction using these card details and you intend to store the card details if the transaction is successful.

sourceOfFunds.type Enumeration OPTIONAL

The payment method used for this payment.

If you are passing card data (in any form) on the API, then you need to set this value, and also provide the card details in the sourceOfFunds.provided.card group. In the case of digital wallets or device payment methods, you must also populate the order.walletProvider field.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.

Value must be a member of the following list. The values are case sensitive.

CARD

Use this value for payments that obtained the card details either directly from the card, or from a POS terminal, or from a wallet, or through a device payment method.

SCHEME_TOKEN

Use this value for payments using scheme tokens provided by Mastercard Digital Enablement Service (MDES), or Visa Token Service (VTS), or American Express Token Service (AETS).

transaction REQUIRED

Information about the transaction.

transaction.creationDate DateTime REQUIRED

The date and time the transaction was created in your system or in the system that you used to submit the transaction to the acquirer.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

transaction.source Enumeration REQUIRED

Indicates the channel through which you received authorization for the payment from the payer.

For example, set this value to INTERNET if the payer initiated the payment online.

If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.

Value must be a member of the following list. The values are case sensitive.

CALL_CENTRE

Transaction conducted via a call centre.

CARD_PRESENT

Transaction where the card is presented to the merchant.

INTERNET

Transaction conducted over the Internet.

MAIL_ORDER

Transaction received by mail.

MERCHANT

Transaction initiated by you based on an agreement with the payer. For example, a recurring payment, installment payment, or account top-up.

TELEPHONE_ORDER

Transaction received by telephone.

VOICE_RESPONSE

Transaction conducted by a voice/DTMF recognition system.

transaction.type Enumeration REQUIRED

Informs the risk service provider about the type of transaction for which you are requesting a risk assessment.

Value must be a member of the following list. The values are case sensitive.

AUTHORIZATION

Authorization

AUTHORIZATION_UPDATE

Authorization Update

CAPTURE

Capture

OTHER

Any other transaction type

PAYMENT

Payment (Purchase)

REFUND

Refund

REFUND_AUTHORIZATION

Refund Authorization

VERIFICATION

Verification

VOID_AUTHORIZATION

Void Authorization

VOID_CAPTURE

Void Capture

VOID_PAYMENT

Void Payment

VOID_REFUND

Void Refund

transaction.url Url OPTIONAL

If transaction.source=INTERNET, provide the URL of the site (including the full path, parameters, port etc.

) on which the payer clicked the 'Pay' button to initiate the payment for this transaction.

Ensure that the URL begins with 'https' and is longer than 11 characters.

transactionProcessingResponse OPTIONAL

Provide this parameter group if you are requesting a risk assessment for a transaction that you have already submitted to the acquirer for processing.

Provide all available details about the transaction processing outcome, based on the response you have received from your acquirer.

transactionProcessingResponse.acquirerCustomData String OPTIONAL

Additional data that you may have received from the acquirer in the transaction response.

Data can consist of any characters

Min length: 1 Max length: 250
transactionProcessingResponse.approvedAmount Decimal OPTIONAL

The amount returned by the acquirer in the transaction response.

Only provide this amount if it differs from the amount you requested.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
transactionProcessingResponse.avsResponseCode Enumeration OPTIONAL

The Address Verification Service (AVS) result returned by the acquirer in the transaction response.

Value must be a member of the following list. The values are case sensitive.

ADDRESS_MATCH

The street address matched. The post conde and cardholder name did not match or were not provided or were provided but not checked.

ADDRESS_ZIP_MATCH

Both the street address and post code matched. The cardholder name did not match or was not provided or was provided but not checked.

NAME_ADDRESS_MATCH

The cardholder name and street address matched. The post code did not match or was not provided or was provided but not checked.

NAME_ADDRESS_ZIP_MATCH

The cardholder name, street address and post code matched.

NAME_MATCH

The cardholder name matched. The post code and street address did not match or were not provided or were provided but not checked.

NAME_ZIP_MATCH

The cardholder name and post code matched. The street address did not match or was not provided or was provided but not checked.

NOT_AVAILABLE

The issuer did not return address verification details.

NOT_REQUESTED

AVS was not requested.

NOT_VERIFIED

The issuer did not provide the AVS because this is an international transaction.

NO_MATCH

No match. The cardholder name, street address or post code did not match or were not provided or were provided but not checked.

SERVICE_NOT_SUPPORTED

AVS is not supported by the acquirer.

ZIP_MATCH

The post code matched. The street address and cardholder name did not match or were not provided or were provided but not checked.

transactionProcessingResponse.cscResponseCode Enumeration OPTIONAL

The Card Security Code (CSC) validation result returned by the acquirer in the transaction response.

Value must be a member of the following list. The values are case sensitive.

MATCH

Valid or matched.

NOT_PRESENT

Merchant indicated CSC not present on card.

NOT_PROCESSED

Not processed.

NOT_SUPPORTED

Card issuer is not registered and/or certified

NO_MATCH

Invalid or not matched.

transactionProcessingResponse.responseCode Enumeration OPTIONAL

The transaction processing result returned by the acquirer in the transaction response.

Value must be a member of the following list. The values are case sensitive.

ACQUIRER_SYSTEM_ERROR

You received a response from the acquirer indicating that the transaction could not be approved because an error occurred within the acquirer's system while attempting to process the transaction.

APPROVED

You received a response from the acquirer indicating that the transaction was approved.

DECLINED

You received a response from the acquirer indicating that the transaction was declined.

DECLINED_CSC

You received a response from the acquirer indicating that the transaction was declined because of the Card Security Code (CSC) not being provided, invalid or not matching.

DECLINED_INVALID_PIN

You received a response from the acquirer indicating that the transaction was declined because of the provided PIN being invalid.

DECLINED_PIN_REQUIRED

You received a response from the acquirer indicating that the transaction was declined because a PIN was required but not provided.

EXPIRED_CARD

You received a response from the acquirer indicating that the transaction was declined because the card has expired.

INSUFFICIENT_FUNDS

You received a response from the acquirer indicating that the transaction was declined because of insufficient funds.

REFERRED

You received a response from the acquirer indicating that the transaction could not be approved and that you need to contact the issuer to retrieve an Authorization Code.

Response

Fields

correlationId String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
id Alphanumeric + additional characters ALWAYS PROVIDED

A unique identifier for this risk assessment to distinguish it from any other risk assessment you create.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'

Min length: 1 Max length: 40
provider CONDITIONAL

Details about the risk service provider for this risk assessment.

provider.name String CONDITIONAL

The name of the risk service provider.

Data can consist of any characters

Min length: 1 Max length: 250
provider.riskAssessmentRequestId String CONDITIONAL

The unique identifier for the risk assessment request submitted to the risk service provider.

The gateway generates this value and submits it in the request to the risk service provider so that you can track the risk assessment in the risk service provider's system.

Data can consist of any characters

Min length: 1 Max length: 100
recommendation Enumeration CONDITIONAL

The overall result of risk assessment returned by the risk service provider.

Value must be a member of the following list. The values are case sensitive.

ACCEPT

The Risk Service Provider assessed the information you submitted in the risk assessment request and considers the risk of completing the transaction as low risk.

NOT_CHECKED

The Risk Service Provider did not risk assess the information you provided in the risk assessment request because the request contained insufficient information to make a risk assessment.

REJECT

The Risk Service Provider assessed the information you submitted in the risk assessment request and considers the risk of completing the transaction as high risk.

REVIEW

The Risk Service Provider assessed the information you submitted in the risk assessment request and considers the risk of completing the transaction as neither low risk or high risk and recommends that you perform a manual review before completing the transaction.

result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the assessment.

Value must be a member of the following list. The values are case sensitive.

FAILURE

The operation was declined or rejected by the gateway, acquirer or issuer

PENDING

The operation is currently in progress or pending processing

SUCCESS

The operation was successfully processed

UNKNOWN

The result of the operation is unknown

review CONDITIONAL

Details of the decision need to make or have made, when the risk service provider has asked to you review this assessment.

review.decision Enumeration CONDITIONAL

The status of the risk review decision.

Where a risk review is required you need to go to the risk service provider's system and make the decision. The decision will then be recorded against the risk assessment.

Value must be a member of the following list. The values are case sensitive.

ACCEPTED

You made a review decision and accepted the payment for processing.

PENDING

A decision to accept or reject the payment for processing is pending.

REJECTED

You made a review decision and rejected the payment for processing.

review.decisionReason String CONDITIONAL

The reason you selected when you reviewed this order in the external risk service provider's system and decided to accept or reject the risk assessment.

Data can consist of any characters

Min length: 1 Max length: 100
review.note String CONDITIONAL

The note that you entered when you reviewed this payment in the risk service provider's system and decided to accept or reject the order.

Data can consist of any characters

Min length: 1 Max length: 2000
review.timeOfDecision DateTime CONDITIONAL

The date and time you made the decision to accept or reject the payment in the risk service provider's system.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

review.userId String CONDITIONAL

The identifier of the person who made the decision to accept or reject the payment in the risk service provider's system.

Data can consist of any characters

Min length: 1 Max length: 40
rule[n] CONDITIONAL

Details of the rules applied by the risk service provider to assess the risk of this payment being fraudulent, as provided by the risk service provider.

rule[n].id String CONDITIONAL

The unique identifier for the rule.

Data can consist of any characters

Min length: 1 Max length: 32
rule[n].name String CONDITIONAL

The name of the rule.

Data can consist of any characters

Min length: 1 Max length: 100
rule[n].score Signed Integer CONDITIONAL

The score resulting from the application of this rule.

A number comprising the digits 0-9, having at least one digit and optionally a leading sign. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#integer.)

Min value: -9999999999999999 Max value: 9999999999999999
totalScore Signed Integer CONDITIONAL

The total of the risk scores for all risk rules applied by the risk service provider when assessing the risk of this payment being fraudulent.

The higher the score, the higher the fraud risk.

A number comprising the digits 0-9, having at least one digit and optionally a leading sign. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#integer.)

Min value: -9999999999999999 Max value: 9999999999999999

Errors

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

Value must be a member of the following list. The values are case sensitive.

INVALID_REQUEST

The request was rejected because it did not conform to the API protocol.

REQUEST_REJECTED

The request was rejected due to security reasons such as firewall rules, expired certificate, etc.

SERVER_BUSY

The server did not have enough resources to process the request at the moment.

SERVER_FAILED

There was an internal system failure.

error.explanation String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field String

Indicates the name of the field that failed validation.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode String

Indicates the code that helps the support team to quickly identify the exact cause of the error.

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Enumeration

Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Value must be a member of the following list. The values are case sensitive.

INVALID

The request contained a field with a value that did not pass validation.

MISSING

The request was missing a mandatory field.

UNSUPPORTED

The request contained a field that is unsupported.

result Enumeration

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

ERROR

The operation resulted in an error and hence cannot be processed.